rbm_tutorial(7)
===============

NAME
----
rbm_tutorial - A tutorial introduction to rbm

DESCRIPTION
-----------

This tutorial will explain how to start using rbm to build rpm and debian
packages for different distributions.

In this example we will package the 'tor' software.

Creating a new workspace
------------------------

The first step is to create a rbm workspace. In this example, we
will use '~/rbm', but you could use anything :

----
$ mkdir ~/rbm
$ cd ~/rbm
----

The first thing to do is to create the main configuration file, which
will contain the configuration for all projects in this workspace. For
now, we will just add the 'compress_tar' option, and add more options
later when needed.

----
$ cat > rbm.conf <<END
compress_tar: xz
END
----

The 'compress_tar' options means that we want tarballs to be compressed
using xz.

Creating a new project
----------------------

We will now add the 'tor' project. To do this we just create the
directory inside the projects directory, and put a 'config' file inside
containing the configuration for the project. The main option that we
will set is 'git_url', which is the url used to clone the git repository
of the software. If your project is using mercurial rather than git,
you could set 'hg_url' instead.

----
$ mkdir -p projects/tor
$ cat > projects/tor/config <<END
git_url: https://git.torproject.org/tor.git
END
----

We can check that the project is correctly defined using the 'projects'
command :

----
$ rbm projects
tor
----

And we can display the tor project configuration using the 'showconf'
command :

----
$ rbm showconf tor
---
git_url: https://git.torproject.org/tor.git
----

Version settings
----------------

The first thing to do when adding a new project is to configure the
'version' settings: rbm needs to be able to compute the version of
the software, for any git commit.

By default, rbm will use the latest tag on which a commit is based as
the version number. Sometimes it works, when the project uses version
numbers as tags, but this is not always the case. Alternatively, you can
define a 'var/version_command' option with a shell script or command that
will print the version number.

For tor, we will use a 'var/version_command' option. The version of the
software is defined in the ChangeLog file, so we will use a simple
command to get it. The tor config file now look like this :

----
git_url: https://git.torproject.org/tor.git
version: '[% exec(c("var/version_command")) %]'
var:
  version_command: perl -ne 'if (m/^Changes in version ([^-]+)-.*$/) { print "$1\n"; exit }' < ChangeLog
----

Using the 'showconf' command, we can check the value of the 'version'
option for different commits :

----
$ rbm showconf tor version --git-hash master
0.2.5.1
$ rbm showconf tor version --git-hash tor-0.2.4.17-rc
0.2.4.17
----

The first time you run this command, the git repository will have to be
cloned, which can take some time.

Creating a tarball
------------------

After setting the configuration for the version, we are now ready to
create a tarball based on a git commit. We can do this using the 'tar'
command :
----
$ rbm tar tor --git-hash master
Created /home/boklm/rbm/out/tor-0.2.5.1.tar.xz
$ rbm tar tor --git-hash tor-0.2.4.17-rc
Created /home/boklm/rbm/out/tor-0.2.4.17.tar.xz
----

Building an rpm package
-----------------------

In order to build rpm packages, you will need to define an rpm step
(see link:rbm_steps.html[rbm_steps(7)]) in rbm.conf.

The rbm.conf file should define an +rpm+ option containing the commands
to build an rpm package:
----
rpm: |
  #!/bin/bash
  [ here the commands for building an rpm package ]
----

Unfortunately, this part of the tutorial, with details about the
definition of the rpm step has not been written yet.

You should be able to start a build with the 'build' command and
the '--step' option:
----
$ rbm build --step rpm tor
----

Building a debian package
-------------------------

Similarly to the rpm package, building debian packages will require that
you define a deb step in rbm.conf. This part of the tutorial has not
been written yet.

Using a build container
-----------------------

Using the remote options (see link:rbm_remote.html[rbm_remote(7)]) you
can do the builds inside containers. Unfortunately this part of the
tutorial has not been written yet. However you can look at the
Tor Browser build repository for an example:
https://gitweb.torproject.org/builders/tor-browser-build.git/

SEE ALSO
--------
link:rbm.html[rbm(1)]
